Adding Activations to Existing Serial Numbers

SoftwareShield CheckPoint™ License Server > CheckPoint License Server Interfaces > HTTP GET URL Interface > Adding Activations to Existing Serial Numbers

## Adding Activations to Existing Serial Numbers

Before you read this section, be sure you are familiar with the basic HTTP GET Interface concepts.

The easiest way to program against the HTTP GET Interface is to construct prototypes of the URL's you will dynamically produce in a simple text editor and call them directly through a browser. The Checkpoint License Server will deliver the responses right into the browser in a readable format and once you have a methodology figured out - you can move to your code and test it programmatically.

When you wish to add activations to existing Serial Numbers, you will always use the "esn" action in the path of the URL you construct (see "Component C").

Be sure to use a valid CheckPoint Administrators credentials in the path as well, right after the action portion. (see "Component D"). Note that they must be passed as <user name>*<password> (separated by an asterisk).

### Parameters

There are a number of parameters you can use to add activations to an existing Serial Number. They are:

Default Query Parameter Name | Map-able to a different Name | Required or Optional | Description
ESN |  | Required | This is the existing Serial Number you wish to add Activations to.
GSN * |  | Optional | This is a special parameter that allows you to compress multiple other URL Encoded parameters in this list into a single parameter value (see below).
QPM * * |  | Optional | Query string parameter name mapping ID that you wish to use to map default query parameter names in this list into your own names.
GSNPAC |  | Required * * * | The number of permitted activations you wish to add to the existing Serial Number. Defaults to 1.
GSNPOAC |  | Required * * * | The number of overflow activations you wish to add to the existing Serial Number. Defaults to 0.

* GSN parameter

The GSN parameter (Generate Serial Number) is a special parameter for your use when you do not have control over a third party caller of your HTTP interface (like a merchant services provider) and you only have access to one free form parameter. You can effectively pass any number of other parameters inside the GSN parameter.

NOTE: If you have control over the parameters passed to the CheckPoint License Servers HTTP Interface (i.e.: you are writing the caller) - you do not have to use a GSN parameter. In this case, it is recommended that you do not use a GSN parameter because it unnecessarily complicates things.

All of the other parameters used for adding activations shown in the table above may be passed inside the GSN parameter value.

In order to embed other parameter values inside the GSN parameter you must URL encode them. Most libraries have the functionality to perform URL encoding for you. However it can be done "manually" if you need. The two most important characters that you must URL Encode are "=" and "&" which are the delimiters for query string parameters. These, when URL Encoded convert to "%3D" and "%26" respectively.

#### Example of how to use the GSN Parameter

Lets say you use a merchant services provider (like Kagi®, SWREG® or Digital River®) to sell your software. These providers do allow you to call a web-deployed program to generate "keys" (Serial Numbers) for your software when they sell a copy. However, they often only provide a single free-form parameter that you can specify an arbitrary value in as input to this program.

Now, a returning client wants to purchase more copies of your software (more activations). You want to call the CheckPoint License Server to add activations to their Serial Number as the result of the sale of the additional seats. But, you only have access to one parameter - and you are required by the CheckPoint server to pass several (ESN,GSNPAC or GSNPOAC). So, you can pass these parameters inside the GSN parameter.

So, let's say you want to pass the following query string to add activations to a Serial Number: Serial Number = AAAA-AAAA-AAAA-AAAA, activations to add = 10, overflow activations to add = 0. Therefore, you would like to pass:

ESN=AAAA-AAAA-AAAA-AAAA&GSNPAC=10 (overflow is not specified because it is optional and defaults to 0.)

But - you only have access to one free-form parameter. So you URL Encode the above query string and use it as the value in the GSN parameter like this:

GSN=ESN%3DAAAA-AAAA-AAAA-AAAA%26GSNPAC%3D10

Notice that above, the "=" has been converted to "%3D" and "&" = "%26". This allows you to pass multiple parameters embedded inside the GSN parameter.

* * QPM parameter (Query Parameter Mapping)

Note that in the above example (Example of how to use the GSN Parameter), you could also "re-name" the free form parameter to anything you needed. For example if the third party only gave you one free-form parameter value to use and it would always be passed as "user_text" you could simply "map" the parameter name "GSN" to "user_text".

Query parameter mapping is covered in more detail in Map CheckPoint HTTP GET Query Parameters.

* * * Serial Number Generation Parameter Value Notes

At least one of the parameters GSNPAC or GSNPOAC must be specified. However, you can also specify them both.

Note that GSNPAC defaults to 1 if you do not specify it and GSNPOAC defaults to 0 if you do not specify it.

#### Examples Calls to Add Activations to an Existing Serial Number:

Because of the length of some of these examples, we have dropped components "A", "B", "C" and "D" and only show component "E" (the parameters). For a review of what the components of the URL are, please see: HTTP GET URL Interface.

In all these examples you can assume that the remainder of the URL shown is prefixed by the HTTP path and application name in exactly the same way (for example they all start with: "https://secure.server.com/cp/checkpoint.dll/esn/admin*password")

- This call adds to an existing Serial Number (FRPL-FUC0-X518-267H), 5 activations and 2 overflow activations. This is the kind of call you would make if you have total control over the names and number of parameters you pass:
  ?esn=FRPL-FUC0-X518-267H&GSNPAC=5&GSNPOAC=2

- This call uses the special GSN parameter to contain the other query parameter names and values. Note that inside the GSN parameter we pass exactly the same parameters as the call above - but as the GSN value. Also, notice that the contained parameters are URL encoded. This is the kind of call you might make if you have control over the name of the free-form parameter, but not the number available (you have only one).
  ?GSN=esn%3DFRPL-FUC0-X518-267H%26GSNPAC%3D5%26GSNPOAC%3D2

- Again, this call uses the special GSN parameter to contain the other query parameter names and values. However, notice here that we have used the QPM parameter to identify a Query Parameter Mapping ID in the database. We previously created a Query Parameter Mapping using the CheckPoint Remote Administrator which mapped the parameter name "fred" to "GSN". Once we created this mapping, we noted that its Query Parameter Mapping ID was 6. Note that inside the GSN parameter (named "fred") we pass in this example are exactly the same parameters as the first example. Also, notice that the contained parameters are URL encoded. This is the kind of call you might make if you have no control over the name of the free-form parameter, and you have only one.
  ?fred=esn%3DFRPL-FUC0-X518-267H%26GSNPAC%3D5%26GSNPOAC%3D2%26QPM%3d6

Note: The SoftwareShield CheckPoint™ License Server only comes with the Server Edition of the SoftwareShield System.